feat: consume @supabase/postgrest-typegen for type generation - #1084

…trospection (#118)

## Summary

Adds an optional `format` callback to `GenerateTypescriptOptions` for
the TypeScript generator, and switches the default formatter itself from
prettier to oxfmt.

This unblocks supabase/postgres-meta#1084, whose description flags that
`@supabase/postgrest-typegen` formats inline with `prettier` and exposed
no formatting hook yet, which that PR states should land here first.
Tracked in Linear as SDK-1649.

The review comment on that PR
(supabase/postgres-meta#1084 (comment))
measured prettier at roughly 73-92% of `generateTypescript`'s time and
made two asks against this package:

1. "A formatter-choice option... worth raising against
`postgrest-typegen` — it already uses `oxfmt`/`oxlint` on its own
source, so the dependency is familiar there." Addressed by the `format`
option.
2. "~90% of type generation is prettier... `oxfmt` is roughly an order
of magnitude faster on this kind of workload." Addressed by switching
the default itself, not just making it overridable.

Neither of these fully eliminates main-thread blocking on its own; that
review's own benchmark achieved its largest win (~1000ms -> ~21ms
main-thread block) by additionally wrapping the *entire*
`generateTypescript()` call in a worker, which is an architecture choice
for the consumer (postgres-meta) to make, not something needed here.

## Changes

- `introspect()` now issues its ten introspection queries under
`Promise.all` instead of awaiting them one at a time. The same review
flagged that postgres-meta's CLI path (`supabase gen types`) went from
parallel to sequential in the migration, adding one round trip per query
on remote databases; this restores the old parallelism for every
consumer. A pooled `Queryable` runs the queries in parallel, a
single-connection one pipelines them.

- `GenerateTypescriptOptions.format?: (code: string) => Promise<string>`
— optional, defaults to a new `oxfmt`-backed formatter (`semi: false`,
`printWidth: 80` to match prettier's default and minimize output churn).
- `prettier` dropped as a dependency; `oxfmt` moves from a devDependency
to a runtime dependency.
- The nightly parity job against real postgres-meta (still
prettier-formatted) now canonicalizes postgres-meta's TypeScript output
through this package's own oxfmt formatter before diffing, so it keeps
catching real content drift without flagging the formatter swap itself
every night.
- `test/parity/expected/typescript.txt` and the inline snapshots in
`test/generation/typescript.test.ts` regenerated for the new formatter's
output. Verified the only remaining differences from the previous
prettier-formatted goldens are formatter style choices (confirmed by
reformatting the old prettier golden through the new oxfmt formatter and
diffing against a fresh regeneration; the only residual difference is
oxfmt adding parentheses around a conditional type in a couple of
generic-default positions, which is semantically inert).

## Test plan

- [x] `bun run check-types`
- [x] `bun run format-and-lint`
- [x] `bun run knip`
- [x] `bun run build`
- [x] `bun run test` (93 pass, including a regression test asserting a
custom `format` callback is invoked and its output is used verbatim)

… Args, trigger-writable views (#125)

## Summary

Ports the worthwhile TypeScript generator fixes from postgres-meta's
open template PRs into this package (the templates are being deleted in
favor of this package in supabase/postgres-meta#1084, so open fixes
there are triaged and re-landed here). Four fixes, one commit each:

1. **Stored generated columns omitted from Insert/Update** (from
supabase/postgres-meta#1105): `GENERATED ALWAYS AS ... STORED` columns
reject writes in Postgres, but only identity-ALWAYS columns were
excluded; both now emit `?: never`.
2. **Non-nullable json narrowed to `NonNullable<Json>`** (from
supabase/postgres-meta#1085): the emitted `Json` type includes `null`,
so a NOT NULL json/jsonb column structurally permitted null. Known
accepted edge: a NOT NULL jsonb column holding a JSON `'null'::jsonb`
value still serializes as JS `null`, so Row is optimistic in that case;
Insert/Update narrowing is fully sound.
3. **Zero-argument function Args typed `Record<PropertyKey, never>`**
(the still-valid half of supabase/postgres-meta#1035): `Args: never`
makes postgrest-js treat every zero-argument function as a computed
field (`never extends { '': Row }` always holds), dropping same-named
columns from `select('*')` results, and an uninhabited `Database` breaks
sound type tooling. Verified against postgrest-js, whose
`IsMatchingArgs` special-cases `Record<PropertyKey, never>`.
4. **Insert/Update types for INSTEAD OF trigger views** (from
supabase/postgres-meta#1062, reimplemented): views made writable by
INSTEAD OF triggers got no Insert/Update types. Views now carry
`is_insert_enabled`/`is_update_enabled` computed via
`pg_relation_is_updatable(oid, true)` (bit 8 INSERT, bit 4 UPDATE; also
covers INSTEAD rules), gated independently, and column updatability
counts triggers too (`pg_column_is_updatable(oid, attnum, true)` plus an
explicit INSTEAD OF INSERT trigger check, since that function only
considers the UPDATE event). The origin PR duplicated hand-rolled
pg_trigger subqueries with one pair of wrong bit values and left
trigger-writable columns degrading to `?: never`, visible in its own
snapshot. The two new `PostgresView` fields are additive (metadata
version stays 1), documented, and mirrored in the frozen equivalence
contract.

## Triage of origin PRs

| postgres-meta PR | Verdict | Reasoning |
|---|---|---|
| #1105 | Ported | Two-line correctness fix; `is_generated` was already
introspected. |
| #1085 | Ported | Nullability chokepoint fix; function returns and
composite attributes untouched. |
| #1035 | Ported (zero-arg half) | The computed-field-filtering half is
superseded: this package introspects with `includeTableTypes: true`, so
table/view row types already resolve (parity golden shows computed
fields working). Only foreign-table row types remain uncovered; the PR's
name-string matching is too fragile to port for that niche. |
| #1062 | Reimplemented | Right idea, broken execution (wrong tgtype
bits in one duplicated subquery pair, all-`never` Update output in its
own snapshot). |
| #1063 (TS part) | Skipped | Superseded: composite attributes already
emit `| null` on main; the PR's remaining delta (`unknown | null`) is
the identical type. |
| #1048 (vector to `number[]`) | Skipped | Wrong as a global remap:
PostgREST serializes pgvector as strings in responses, so Row types
would regress; the reviewer asked for e2e evidence and got none. Needs
input/output-aware mapping, a design discussion. |
| #973 (`| string` numeric inserts) | Skipped | Maintainer requested
changes: breaking for consumers expecting `number`; per-column overrides
are the escape hatch. |
| #573 | Skipped | Blanket `| null` on function args/returns is breaking
(author concedes); the centralization half is superseded by the current
generator; the domain-resolution gap is real but needs a metadata
contract extension (feature-scale, raised separately). |
| #750 (`Json` to `unknown`) | Skipped | Breaking; major-version
decision. |
| #1044 (int8 to `bigint`) | Skipped | Breaking, and incorrect without a
custom JSON parser. |
| #1083 (`bigint_as` option) | Skipped | Feature/option with API design
questions, not a fix. |
| #814 (json_schema constraint types) | Skipped | New feature. |

## Validation

- Unit tests per fix, plus Docker-backed introspection integration tests
proving a join view with an INSTEAD OF INSERT trigger introspects as
insert-enabled/update-disabled with updatable columns, and
auto-updatable views keep both flags.
- Parity golden regenerated and reviewed line by line: the only change
is 14 zero-argument functions switching `Args: never` to `Args:
Record<PropertyKey, never>`. Fixes 1, 2 and 4 have no fixture-visible
effect.
- `check-types`, `format-and-lint`, `knip`, `build`, `test` (99 pass
across 12 files) all green.
- Note: the nightly parity job against real postgres-meta will show this
intentional drift until postgres-meta consumes a release containing it
(supabase/postgres-meta#1084 replaces the templates with this package,
closing the gap).

…ls (#123)

## Summary

Ports the Swift string literal escaping fix from postgres-meta's open
template PRs into this package (the templates are being deleted in favor
of this package in supabase/postgres-meta#1084, so open fixes there are
triaged and re-landed here).

Database-provided names were interpolated raw into Swift string
literals, so a double quote, backslash (including interpolation
sequences like `\(...)`), or line break in an enum label or column name
produced Swift that does not compile (supabase/postgres-meta#1126). A
`swiftStringLiteral` helper now escapes per Swift's string literal
grammar (backslash, quote, tab, newline, carriage return, remaining C0
controls and DEL as `\u{n}`, plus U+2028/U+2029) and is applied in
`generateEnum`, the single rendering point for both vulnerable
positions: Postgres enum raw values and `CodingKeys` raw values.

## Triage of origin PRs

| postgres-meta PR | Verdict | Reasoning |
|---|---|---|
| #1128 | Ported | The stronger duplicate: character-loop escaping
covering controls and U+2028/U+2029, returns the complete quoted
literal, and the author validated output with `swiftc -parse`. |
| #1132 | Skipped | Duplicate; regex-based, misses U+2028/U+2029, and
returns only inner text so call sites keep hand-placed quotes. The regex
would also trip oxlint's control-character rule here. |

Identifier positions (enum case names, property names) are already safe
through the existing
`formatForSwiftTypeName`/`formatForSwiftPropertyName` sanitization, so
escaping is only needed at the literal seam. Pre-existing identifier
gaps (all-punctuation names yielding empty case names, leading digits)
exist upstream too and need a separate sanitization/dedup design;
deliberately out of scope.

## Validation

- Snapshot test with pathological labels (quote, backslash, `\(now)`,
newline, tab, CR, BEL, U+2028) across enum raw values and CodingKeys in
Select/Insert/Update, plus a pin that ordinary output stays
byte-identical.
- Generated pathological output passes `swiftc -parse`.
- `check-types`, `format-and-lint`, `knip`, `build`, `test` (95 pass,
parity 4/4) all green; parity golden unchanged.

## Summary

Bumps the pinned pg-meta image from `v0.98.0` to `v0.99.0` in the shared
service-image manifest (`apps/cli-go/pkg/config/templates/Dockerfile`,
imported by the TypeScript CLI as its image source).

postgres-meta v0.99.0 replaces the embedded type-generation templates
with the shared
[`@supabase/postgrest-typegen`](https://github.com/supabase/sdk/tree/main/packages/postgrest-typegen)
package (supabase/postgres-meta#1084). This is part of a coordinated
rollout with the hosted path (supabase/platform#37764) so `gen types`
produces the same output locally and via `--project-id`.

## Relationship to supabase#6404

supabase#6404 makes `gen types` run postgrest-typegen in-process, removing the
pg-meta container from that command entirely. This pin still matters
independently of it: the same manifest entry provides the `pgmeta`
service that `supabase start` runs for Studio's local API, and it covers
`gen types` for any release cut before supabase#6404 lands. The two do not
conflict (different files), and output is consistent either way since
v0.99.0 serves the same generator package that supabase#6404 embeds.

## What changes for users

Generated TypeScript output changes in two deliberate ways:
deterministic metadata ordering (a one-time reordering diff when
regenerating existing types) and oxfmt formatting instead of prettier
(style-only). Content is otherwise unchanged.

## Validation

- `go build ./...` passes in both modules.
- The pre-existing `gen types` e2e tests pull this image tag directly,
so CI exercises the new release; the image is published on Docker Hub
and ECR Public.

… names (#122)

## Summary

Ports the Go struct tag escaping fix from postgres-meta's open template
PRs into this package (the templates are being deleted in favor of this
package in supabase/postgres-meta#1084, so open fixes there are triaged
and re-landed here).

A backtick in a column name terminated the raw struct tag literal and
produced unparseable Go (supabase/postgres-meta#1125). Tag values are
now built with `JSON.stringify` (JSON escape sequences are a strict
subset of Go's, so `reflect.StructTag.Get` recovers the exact name via
`strconv.Unquote`), and tags containing a backtick fall back to an
interpreted string literal. Ordinary names keep the exact raw-literal
form, so normal output is byte-identical and the parity golden is
unchanged.

## Triage of origin PRs

| postgres-meta PR | Verdict | Reasoning |
|---|---|---|
| #1127 | Ported | The stronger duplicate: escapes quotes, backslashes
and control characters too, matching this package's existing
`JSON.stringify` escaping precedent. |
| #1131 | Skipped | Duplicate of #1127; only switches literal forms and
leaves quotes unescaped, so `a"b` produced a tag that
`reflect.StructTag.Get` misparses (its own test pins the broken output).
|

Known limitation, documented in the code: names that `encoding/json`
itself rejects as tag names (commas, quotes, backticks) still compile
and round-trip through `reflect.StructTag`, but the marshaler falls back
to the Go field name at runtime; that is a limitation of the struct tag
convention, not the generated source. Output for the pathological cases
was validated against real Go (gofmt parse + `reflect.StructTag.Get`
round-trip).

## Validation

- Seven new unit tests (ordinary pinned byte-identical, backtick, quote,
backslash, control character, combined, composite attribute).
- `check-types`, `format-and-lint`, `knip`, `build`, `test` (100 pass,
including Docker-backed parity) all green.
- Parity golden unchanged. Note: the nightly parity job against real
postgres-meta will only show drift for schemas with pathological column
names, which the fixture does not contain.

…columns, composite nullability (#124)

## Summary

Ports the worthwhile Python generator fixes from postgres-meta's open
template PRs into this package (the templates are being deleted in favor
of this package in supabase/postgres-meta#1084, so open fixes there are
triaged and re-landed here). Four fixes, one commit each:

1. **Identifier escaping** (from supabase/postgres-meta#1082): enum
`Literal` labels and `Field(alias=...)` values were interpolated
unescaped, so a quote, backslash, or newline in a database name broke
the generated module. A shared `escapePythonString` helper (JSON
escaping, a strict subset of Python's) now covers all three
interpolation sites.
2. **Python 3.9/3.10 support** (from supabase/postgres-meta#1094):
`NotRequired` (3.11+) and `TypeAlias` (3.10+) now import from
`typing_extensions`, which is always installed as a required dependency
of pydantic.
3. **Deserialized json/jsonb** (from supabase/postgres-meta#1129):
`json`/`jsonb` map to pydantic's `JsonValue` instead of `Json[Any]`.
PostgREST returns these columns already deserialized, while `Json[Any]`
validates a JSON *string* and parses it, so every generated model with a
JSON column failed `model_validate` (supabase/supabase-py#1597).
4. **Composite type nullability** (the Python side of
supabase/postgres-meta#1063, reimplemented): composite type attributes
cannot carry NOT NULL constraints in Postgres, so their fields now emit
`Optional[...]`. The origin PR's Python hunks were dead code (an unused
`PythonDomain` class and a type-map entry for a name Postgres never
emits), so the actual fix was implemented instead of ported.

## Triage of origin PRs

| postgres-meta PR | Verdict | Reasoning |
|---|---|---|
| #1082 | Ported | Real invalid-syntax bug, correct approach. |
| #1094 | Ported | Import failure on Python 3.9/3.10, independently
verified by community comments on the PR. |
| #1129 | Ported | Every JSON column failed validation at runtime;
`JsonValue` is pydantic's native type for a parsed JSON value. |
| #1063 (python part) | Reimplemented | Real bug, but the PR's Python
changes did not actually fix it (dead code); the underlying fix is one
line in `typeToClass`. |
| #1072 (`frozen=True`) | Skipped | Author-labeled feature and an
opinionated behavior change that breaks consumers who mutate row models;
belongs behind a generator option if wanted. |
| #808 | Skipped | 2023 draft fully superseded by the
maintainer-authored template this package ports. |

## Validation

- Unit tests per fix (pathological enum labels and aliases, import block
assertions, json/jsonb mapping, composite `Optional` fields).
- Parity golden regenerated (39 lines): the `typing_extensions` import
split, 16 `Json[Any]` to `JsonValue` occurrences, and two composite
attributes gaining `Optional[...]`; reviewed line by line and the golden
gate was verified to actually trip on corruption.
- The regenerated golden imports cleanly under pydantic, passes `mypy`,
and runtime checks confirm deserialized JSON and `None` composite fields
now validate.
- `check-types`, `format-and-lint`, `knip`, `build`, `test` (97 pass,
includes Docker-backed introspection and parity) all green.
- Note: the nightly parity job against real postgres-meta will show this
intentional drift until postgres-meta consumes a release containing it
(supabase/postgres-meta#1084 replaces the templates with this package,
closing the gap).